package me.flyray.bsin.facade.engine;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import me.flyray.bsin.domain.entity.ChainCoin;
import me.flyray.bsin.domain.entity.ContractProtocol;
import me.flyray.bsin.domain.entity.DidProfile;
import me.flyray.bsin.domain.request.ChainCoinDTO;

import java.util.Map;

/**
 * DID身份档案服务引擎接口
 * 
 * 功能概述：
 * 基于DID（去中心化身份）技术的身份档案管理系统，是整个身份体系的档案层
 * 
 * 架构关系：
 * - 基础层：DID（去中心化身份标识）
 * - 档案层：Profile（本接口管理的身份档案）1:1 映射DID
 * - 会员层：PassCard（基于Profile创建的品牌会员卡）1:N 关联Profile
 * - 应用层：Wallet、Agent等（基于PassCard提供具体服务）
 * 
 * 核心概念：
 * - DID：全局唯一的去中心化身份标识符，确保身份不可篡改
 * - Profile：基于DID的丰富身份档案，包含个人/品牌的详细信息
 * - 身份类型：Individual（个人）、Brand（品牌）、Device（设备）
 * 
 * 业务流程：
 * 1. 创建DID身份（本接口）
 * 2. 建立Profile档案（本接口）
 * 3. 基于Profile开通PassCard会员卡
 * 4. PassCard自动生成TBA钱包和Agent数字分身
 * 
 * 技术特点：
 * - 基于区块链的可信身份管理
 * - 支持多种身份类型和业务角色
 * - 提供数字签名和验签能力
 * - 确保身份数据的安全和隐私
 * 
 * @author bolei
 * @date 2023/6/26
 * @desc DID身份档案管理服务引擎 - 身份体系的档案层
 */
public interface DidProfileServiceEngine {

    /**
     * 创建DID身份档案
     * 
     * 功能说明：
     * - 创建DID去中心化身份标识符
     * - 建立基于DID的身份档案（Profile）
     * - 支持个人、品牌、设备等多种身份类型
     * - 完成身份认证和档案信息录入
     * 
     * 架构位置：身份体系的基础层+档案层
     * 后续流程：Profile → PassCard → Wallet/Agent
     * 
     * 身份类型：
     * - Individual：个人用户（需要实名认证）
     * - Brand：品牌商户（需要企业认证）
     * - Device：IoT设备（需要设备认证）
     * 
     * 技术实现：
     * - 调用可信数据空间创建DID标识符
     * - 生成DID文档和私钥数据
     * - 保存Profile档案信息到数据库
     * - 关联业务角色和租户信息
     * 
     * @param requestMap 创建参数，包含：
     *                  - type: 身份类型（Individual/Brand/Device）
     *                  - name: 档案名称（真实姓名/品牌名称）
     *                  - category: 身份分类
     *                  - tenantId: 租户ID
     * @return DidProfile 创建成功的身份档案，包含DID和Profile信息
     */
    DidProfile create(Map<String, Object> requestMap) throws Exception;


    /**
     * DID身份数字签名
     * 
     * 功能说明：
     * - 使用DID私钥对数据进行数字签名
     * - 确保数据来源的真实性和完整性
     * - 支持跨平台的身份验证
     * 
     * 应用场景：
     * - PassCard开卡时的身份验证
     * - 链上交易的身份确认
     * - 跨平台数据授权
     * - Agent代理操作的身份证明
     * 
     * @param requestMap 签名参数，包含：
     *                  - did: DID标识符
     *                  - data: 要签名的原始数据
     * @return Map 签名结果，包含signature、timestamp等
     * @throws Exception 签名过程中的异常
     */
    Map<String, Object> signData(Map<String, Object> requestMap) throws Exception;

    /**
     * DID身份签名验证
     * 
     * 功能说明：
     * - 验证DID数字签名的有效性
     * - 确认操作者的身份真实性
     * - 防止身份伪造和数据篡改
     * 
     * 验证流程：
     * 1. 根据DID查询对应的公钥
     * 2. 使用公钥验证签名
     * 3. 检查数据完整性
     * 4. 返回验证结果
     * 
     * @param requestMap 验证参数，包含：
     *                  - did: DID标识符
     *                  - data: 原始数据
     *                  - signature: Base64编码的签名
     * @return Map 验证结果，包含verified、message等
     * @throws Exception 验证过程中的异常
     */
    Map<String, Object> verifySign(Map<String, Object> requestMap) throws Exception;

    /**
     * 分页查询DID身份档案列表
     * 
     * 功能说明：
     * - 分页查询租户下的所有身份档案
     * - 支持按身份类型、角色类型等条件筛选
     * - 用于身份档案的管理和统计
     * 
     * @param requestMap 查询参数，包含分页信息和筛选条件
     * @return IPage<?> 分页结果
     */
    IPage<?> getPageList(Map<String, Object> requestMap);

    /**
     * 查询DID身份档案详情
     * 
     * 功能说明：
     * - 根据DID或档案ID查询详细信息
     * - 路由到不同类型的身份信息
     * - 为PassCard开卡提供身份验证基础
     * 
     * 查询维度：
     * - 按DID标识符查询
     * - 按档案序列号查询
     * - 按业务角色类型查询
     * 
     * @param requestMap 查询参数，包含DID或档案ID
     * @return DidProfile 身份档案详情，如果不存在则返回null
     */
    public DidProfile getDetail(Map<String, Object> requestMap);

}
